HS_BIBLE.txt

doclib\HSP Document Library\HS_BIBLE.txt » Plain Format

━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
                                                           2006/07/16
  hs ファイル仕様書 Version 2.0

  S.Programs 2001-2006
                                         http://sprocket.babyblue.jp/
━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━

■ はじめに
‾‾‾‾‾‾‾‾‾‾‾‾‾‾‾‾‾‾‾‾‾‾‾‾‾‾‾‾‾‾‾‾‾‾‾
このドキュメントは、HSP ヘルプマネージャ用のヘルプファイルである「hs ファイル」
の仕様を定義するものです。

本書で定義する hs ファイル仕様 (Version 2.0) は、原型の HSP HELP Tools もしくは 
HSP HELP Browser 1.x の仕様で書かれた hs ファイルに対して上位互換であると共に、
より柔軟でシンプルな書式にも対応したものとなっています。

本ドキュメントでは、HSP HELP Tools / HSP HELP Browser 1.x の hs ファイル仕様を
特に区別する場合、「旧仕様」と呼ぶ場合があります。



■ 改定履歴
‾‾‾‾‾‾‾‾‾‾‾‾‾‾‾‾‾‾‾‾‾‾‾‾‾‾‾‾‾‾‾‾‾‾‾
2004/04/07 (HSP HELP Browser 1.40 実装)
・作成

2005/05/25 (HSP HELP Browser 1.50 実装)
・行頭の特殊文字 '%', '^' のエスケープ仕様を追加
・パラメータ書式の関数型表記仕様を追加
・重複するシンボル名のリネームを廃止

2006/07/16 (hs ファイル仕様 Version 2.0)
・グローバルメンバ、ローカルメンバの区別を撤廃
・新フィールドタグ %port, %portinfo に対応
・差分記述の仕様を追加
・行頭の特殊文字 '^' のエスケープ仕様の削除
・容量制限の記述を削除
・用語の一般化
 - ページ → 「レコード」
 - メンバ → 「フィールド」
 - メンバ定義キーワード → 「フィールドタグ」



■ 用語の定義
‾‾‾‾‾‾‾‾‾‾‾‾‾‾‾‾‾‾‾‾‾‾‾‾‾‾‾‾‾‾‾‾‾‾‾
・hs ファイル
ヘルプマネージャ用のヘルプ情報が格納されたテキストファイルを「hs ファイル」とい
います。拡張子は hs です。文字コードは、Shift_JIS を用います。

・レコード
HSP で使われる特定のシンボル (命令など) について説明した、解説文やサンプルスクリ
プトなどのデータ (フィールド) のひとまとまりをレコードと呼びます。ヘルプページの
1 ページが、1 レコードに当たります。hs ファイルには、一つ以上のレコードが含まれ
ることになります。

・フィールド
フィールドとは、レコードに含まれる各要素のことです。命令名や見出し、解説文などが
それに当たります。すべてのフィールドは文字列データとなっています。

ヘルプデータは、レコード×フィールドの、単純なカード型のデータベースとして扱われ
ます。



■ 基本書式
‾‾‾‾‾‾‾‾‾‾‾‾‾‾‾‾‾‾‾‾‾‾‾‾‾‾‾‾‾‾‾‾‾‾‾
hs ファイル形式は、プレーンテキスト・データベースのヘルプ情報を記述するフォーマ
ットです。基本的に、テキスト文章をファイルにそのまま記述していく形式となります。

レコードとフィールドを制御するために、文字 '%' で始まる「フィールドタグ」を使用
します。フィールドタグは、そのタグ以降に記述されるテキストがどのフィールド・レコ
ードに属するかを宣言します。

フィールドタグには、下記の種類があります。

  (タグ)    (内容)
・%index    シンボル名, 見出し
・%prm      パラメータリスト, パラメータ説明文
・%inst     解説文
・%sample   サンプルスクリプト
・%href     関連項目
・%dll      使用プラグイン/モジュール
・%ver      バージョン
・%date     日付
・%author   著作者
・%url      関連 URL
・%note     備考 (補足情報等)
・%type     タイプ
・%group    グループ
・%port     対応環境
・%portinfo 移植のヒント

フィールドタグは、行の頭に書く必要があります。大文字、小文字は区別されません。フ
ィールドの値は、フィールドタグの次の行から、次のフィールドタグの前の行、もしくは
ファイルの終了までに書かれたテキストデータとなります。フィールドタグは、どのよう
な順番で記述してもかまいません。

%index は特に重要かつ特殊なタグで、フィールドの制御だけでなくレコードの区切りを
行う役目を持っています。一つのレコード内の情報は、%index から、次の %index もし
くはファイルの終了までに書かれた値となります。よって、hs ファイルに含まれるレコ
ードは、そのファイル内の %index の数だけ存在することになります。

また、ファイルの先頭から最初の %index までにフィールドタグで記述された値は、その
hs ファイルのすべてのレコードのデフォルトの値となります。たとえば、最初の %index 
までに %port で対応環境を記述しておくと、その hs ファイルに含まれるレコードのう
ち %port タグを含まないものは、すべて最初に記述された値が採用されます。明示的に 
値が設定された場合は、そちらが優先されます。

hs ファイル中に不明なフィールドタグ (例 : %hoge) がある場合は、その中の値は無視
されます。また、ファイル先頭から最初のフィールドタグまでに含まれる文字列も同様に
無視されます。

※
説明文の中などで '%' で始まる行がある場合は、行頭を '%%' とすることでフィールド
タグとして認識しないようにすることができます。



■ 各フィールドの書式
‾‾‾‾‾‾‾‾‾‾‾‾‾‾‾‾‾‾‾‾‾‾‾‾‾‾‾‾‾‾‾‾‾‾‾
各フィールドの記述ルールの説明の前に、すべてのフィールドに共通のルールを説明しま
す。

シンボル名 (%index) 以外のすべてのフィールドは省略可能です。記述が省略され、デフ
ォルト値も記述されていないフィールドの値は、空になります。

文章の改行はビューアーの表示サイズに応じた自動折り返しとなりますので、文の途中で
改行を行わないで、段落ごとに改行を行うことを推奨します。また、英字、数字はなるべ
く半角文字を使用することを推奨します。

各フィールド個別の記述ルールは、以下のようになります。

◆ %index (シンボル名, 見出し)
シンボル名と見出しを記述します。1 行目にシンボル名、2 行目に見出しを記述してくだ
さい。このフィールドタグが、レコードの記述の開始地点となります。シンボル名の省略
はできません。

見出しは、シンボルの機能を簡潔に表した、なるべく短いものにしてください。見出しに
は改行は使えません。


◆ %prm (パラメータリスト, パラメータ説明文)
命令やマクロのパラメータを記述します。1 行目にパラメータリスト (パラメータ書式)、
2 行目以降は各パラメータの概要を記述してください。

パラメータを持たないシンボルの場合は、"パラメータ無し" 等と書かないで、フィール
ドタグの記述を省略してください。また、パラメータを関数式記述にする場合は、パラメ
ータリストを括弧 ( ) で囲んでください。


◆ %inst (解説文)
解説文を記述します。

この部分がヘルプページのメインとなります。表示されるときに等幅フォントが使用され
るため、等幅用に作られた、記号を用いた図表がずれないで表示できます。


◆ %sample (サンプルスクリプト)
サンプルスクリプトを記述します。

行の 1 文字目がセミコロン ';' の場合、hs ファイルのコメントとして扱われ、行が無
視されますので注意してください。


◆ %href (関連項目)
関連するシンボルを、改行区切りで記述します。


◆ %dll (使用プラグイン/モジュール)
使用するプラグインやモジュールがある場合、その名称を記述します。一行のみ書くこと
ができます。

HSP 標準機能でないヘルプでは、この記述は省略できません。DLL を使用しないモジュー
ルであっても、モジュールファイル名などを記述する必要があります。


◆ %ver (バージョン)
バージョンを記述します。一行のみ書くことができます。


◆ %date (日付)
日付を記述します。更新履歴などのために必要であれば、複数行にわたって書くことがで
きます。


◆ %author (著作者)
著作者名を記述します。連名にする場合は、複数行で書きます。


◆ %url (関連 URL)
関連する URL を記述します。複数の URL を記述する場合は、複数行にします。


◆ %note (備考)
備考や注意書きがあれば記述します。複数行にわたって記述できます。


◆ %type (タイプ)
シンボルのタイプを記述します。記述例は "拡張命令", "ユーザー拡張命令" などです。
一行のみ書くことができます。


◆ %group (グループ)
機能を分類するグループを記述します。記述例は、"画面制御命令", "文字列操作命令", 
"入出力制御命令" などです。一行のみ書くことができます。


◆ %port (対応環境)
どのプラットフォームの HSP 実行環境に対応するかを表すフラグ文字列を記述します。

フラグ文字列は、大文字、小文字まで正確に記述してください。複数のプラットフォーム
で実行できる場合、複数行に分けて書きます。現在決まっているフラグは、下記のものが
あります。

 (フラグ)  (環境)
・Win      Windows 版 HSP
・Mac      Macintosh 版 HSP
・Let      HSPLet
・Cli      コマンドライン版 HSP


◆ %portinfo (移植のヒント)
プラットフォーム間の移植についてのヒントを記述します。



■ フィールドの差分記述
‾‾‾‾‾‾‾‾‾‾‾‾‾‾‾‾‾‾‾‾‾‾‾‾‾‾‾‾‾‾‾‾‾‾‾
下記のフィールドタグは、(最初の %index までに書かれる) デフォルト値に対する差分
の記述をサポートします。

・%port+    対応環境フラグへ追加
・%port-    対応環境フラグから除外

たとえば、下記のような hs ファイル記述がある場合、

- - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - 
%port ; デフォルト
Win
Let

%index
test1
%port+ ; 差分 (追加)
Mac

%index
test2
%port- ; 差分 (除外)
Let
- - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - 

シンボル test1 の %port フィールドの値は、デフォルト値に Mac を追加した 3 行とな
り、test2 の %port フィールドの値は、デフォルト値から Let を除外した 1 行となり
ます。

一つのレコードで %port+ と %port- を両方記述することもできます。また、追加時に、
すでに含まれるフラグは重複しての追加はされません。



■ 旧仕様との互換性について
‾‾‾‾‾‾‾‾‾‾‾‾‾‾‾‾‾‾‾‾‾‾‾‾‾‾‾‾‾‾‾‾‾‾‾
本書の hs ファイル仕様のバージョンでは、HSP HELP Tools および HSP HELP Browser 
1.x の仕様 (旧仕様) に存在した「グローバルメンバ」と「ローカルメンバ」の区別がな
くなり、すべてのフィールドをユニバーサルに扱う、シンプルな仕様に変更されました。

旧仕様では、%dll, %ver, %date など 7 種類のフィールドは「グローバルメンバ」と呼
ばれ、一つの hs ファイルに一種類の値しか定義できませんでした。これに対し本書の 
hs ファイル仕様では、すべてのフィールドにおいてレコードごとに異なる値を持つこと
ができます。

最初の %index までに記述されたフィールド値が、それ以降に記述されるレコードのデフ
ォルト値として採用される仕様となっているため、本書の仕様に準拠したヘルプツールは
旧仕様で書かれた hs ファイルに対しても完全な互換性を持ちます。

これにより、異なるプラグイン/モジュールに依存する命令のヘルプを一つの hs ファイ
ルにまとめたり、hs ファイル内の多くのレコードで同じ内容となるフィールドの値を一
度の記述で済ませたりと、柔軟な記述が出来るようになりました。

※
旧仕様のヘルプツールと互換性のある hs ファイルを書く場合は、下記のフィールドタグ
は最初の %index までに記述してください。

・%dll      使用プラグイン/モジュール
・%ver      バージョン
・%date     日付
・%author   著作者
・%url      関連 URL
・%note     備考 (補足情報等)
・%type     タイプ

また、旧仕様では下記のフィールドタグは最初の %index より後にしか記述できません。

・%prm      パラメータリスト, パラメータ説明文
・%inst     解説文
・%sample   サンプルスクリプト
・%href     関連項目
・%group    グループ

下記のフィールドタグは、旧仕様ではサポートされません。

・%port     対応環境
・%portinfo 移植のヒント

同様に、差分記述方式のタグも旧仕様ではサポートされません。



■ タグ ( ^ ) の扱い
‾‾‾‾‾‾‾‾‾‾‾‾‾‾‾‾‾‾‾‾‾‾‾‾‾‾‾‾‾‾‾‾‾‾‾
HSP HELP Tools では、"^" もしくは "^p" と書かれた行をタグといい、テキストの処理
を制御する役割を持っています。

本書の hs ファイル仕様ではこのタグは使用されておらず、"^" もしくは "^p" とだけ書
かれている行は単なる空行として処理されます。そうでない行は、行頭文字が '^' であ
ってもそのまま表示されます。たとえば、"^a" と書かれた行は、そのまま表示されます。



■ コメントについて
‾‾‾‾‾‾‾‾‾‾‾‾‾‾‾‾‾‾‾‾‾‾‾‾‾‾‾‾‾‾‾‾‾‾‾
セミコロン文字 ';' で始まる行はコメントとみなされ、無視されます。また、'%' で始
まるタグ行では、タグ文字列以降の ';' からコメントとして扱われます。

(コメントの例)
; -------- comment
%index ; -------- comment

特にサンプルスクリプト中でスクリプトのコメント用に ';' を使う場合は、それを行頭
に書かないように注意してください。';' の前にスペースやタブがある場合はコメントと
みなされません。



■ hs ファイルの記述例
‾‾‾‾‾‾‾‾‾‾‾‾‾‾‾‾‾‾‾‾‾‾‾‾‾‾‾‾‾‾‾‾‾‾‾
;---------------------------------------------------------------
; hs ファイル サンプル
; (hs specification version 2.0)
;---------------------------------------------------------------

%dll ; モジュールの名前
hhx_db.hsp

%ver
2.0

%date
2006/07/16

%author
sprocket

%url
http://sprocket.babyblue.jp/

%note
hhx_db.hsp をインクルードすること。

%type
ユーザー拡張命令

%group
hs データベース処理

%port
Win

; ここまでに定義されたフィールドの値が、以降のレコードのデフォルト値となります。
;---------------------------------------- record start
%index
HHX_init_load_db
hs データベースをロード

%inst
カレントディレクトリにある hs データベースファイル (hhx.db) をロードします。この
命令が成功した場合、システム変数 stat に 0 が返ります。

hs ファイルが更新されている場合や、hhx.db が存在しない場合は、stat に 1 が返りま
す。その場合は、HHX_init_rebuild_db 命令で hhx.db を再構成してください。

HHX_init_load_db, HHX_init_rebuild_db の実行後には、HHX_init_extract_db 命令でロ
ードしたデータベースをメモリ上に展開する必要があります。

%sample
#include "hhx_db.hsp"

	; HHX データベース ロードシーケンス
	mes "loading..."
	HHX_init_load_db
	if stat {
		mes "rebuilding db..."
		HHX_init_rebuild_db
	}
	HHX_init_extract_db
	mes "complete."

%href
HHX_init_rebuild_db
HHX_init_extract_db

;---------------------------------------- record start
%index
HHX_select_where
hs データベース 検索実行

%prm
("str", FID, XID)
"str" : 検索する文字列
FID   : 完全一致を要求するフィールドの ID
XID   : 検索結果から除外するレコード ID

%inst
hs データベースから文字列 "str" を検索し、検索結果の数を返します。検索文字列は、
大文字小文字、全角半角 の区別はされません。

FID にフィールド ID (C_XXXX) を指定すると、そのフィールドが検索文字列と完全一致
するフィールドのみを列挙します。何も指定しない場合は、-1 としてください。

XID には、検索結果から除外するレコード ID を指定します。何も指定しない場合は、
-1 としてください。

検索結果のレコードの ID は、HHX_get_next() 関数で順に取り出すことができます。

%sample
	; "test" を含むレコードのリストを表示
	repeat HHX_select_where("test", -1, -1)
		c = HHX_get_next()
		mes hhxdata.c.C_NAME + " - " + hhxdata.c.C_SUMMARY
	loop

%href
HHX_find_next
HHX_exist



━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━